home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Atari Mega Archive 1
/
Atari Mega Archive - Volume 1.iso
/
program
/
wx_lib10.zoo
/
wx_lib.doc
< prev
next >
Wrap
Text File
|
1992-08-02
|
9KB
|
252 lines
wx_lib 1.0 documentation
Code and text, Copyright 1992, Michael Alan Dorman.
Contacting me:
M.DORMAN2 on GEnie.
mad@sss.cba.ua.edu on the Internet.
Contact me if you have any suggestions or improvements. However,
I've spent a lot of time making this thing work with at least
two compilers, and I won't really consider any sort of hacks
that are terribly compiler specific. I also won't consider
hacks that will make it break on future versions of TOS/GEM. If
you feel that your change must make it to the public, you're
welcome to release it, but credit me as the original author, and
NAME IT SOMETHING ELSE.
Just for the litigious pedants:
I make no warranty as to the correct operation of this library,
and will not be liable for damage that occurs from the use or
misuse of it.
What you're reading:
This is the documentation for the Extended Window Library I'm
working on. It's being written as the library is forming up, so
it's going to be pretty hectic. I imagine it'll get edited a
lot as I go along, and probably need more than it gets.
The source to the library is included. Don't feel hesitant to
examine it. None of it's very sophisticated.
One caveat: The library almost needs its own VDI workstation.
If you don't use a workstation for anything other than this
library, you're fine. If you don't change the fill color, the
fill pattern, or the text color or alignment, you don't need
another workstation. If you change any of the above, you do,
because in order to speed things up, I went ahead and decided
that the library wouldn't have to re-set things in a million
different places just to be careful. Thus, all the settings are
made in the wx_init() call, and they're assumed to stay valid
from there on out. If you change them, well, you'll have to be
sure to change them back before you make any wx_lib calls.
Usage:
I've gotten this thing to compile and run using both GCC 2.1 and
the GNU-crew's GEM libraries, and HSC 1.40 with GemFast 1.8. It
should work fine with HSC 1.33i and GemFast 1.7, though I
haven't tested it. I've included a wx_lib.a file for HSC 1.40,
and a wx_lib.olb for GCC 2.1.
If you find things that need to be, say, #ifdef'd to make it
work with another compiler, please contact me--I want this thing
to be as general as possible.
The file wx_tst.c is a test program for the library. It uses
all of the library functions, at one time or another. Look at
it. It's short and to the point. The files wx_tst_h.prg and
wx_tst_g.prg are two different executables of the exact same
source file, one compiled with HSC 1.40 (_h.prg) and one with
GCC 2.1 (_g.prg). They both run pretty fast.
Function descriptions:
I'm just going to enumerate and describe the individual
functions in alphabetical order, just to make it easy.
void wx_clear(ws)
Window *ws;
This functions clears the interior of the window by drawing a
filled rectangle of the proper size in the window's work space.
It is, by default, set to be drawn in color 0--the default color
being white on STs.
void wx_close(ws)
Window *ws;
This function closes and deletes the window in question. It
doesn't reset the parameters of the Window structure, so you can
use it again with another call to wx_open().
void wx_free(ws)
Window *ws;
It occured to me that with GemFast 1.8, you can simply call
apl_vopen() to open a VDI workstation, and that returns the VDI
handle. Which would allow you, in a perfect world, to just call
wx_init(&ws,apl_vopen(),gl_wchar,gl_hchar). Thus you'd never
see the VDI handle. All this function does is close the VDI
workstation that you've assigned to the wx_lib functions,
without having to directly modify any values in the structure.
void wx_fscroll(ws)
Window *ws;
This is a function that is primarily used internally by the
library to scroll the window forward. It automatically scrolls
the window by the number of lines in the ws->scrl variable. It
uses a standard vro_cpyfrm() call to do it.
void wx_full(ws)
Window *ws;
This function opens the window to its declared full parameters,
which default to being the size if the full desktop, if the
values aren't changed before the wx_open() call.
void wx_get(ws)
Window *ws;
This function uses the standard wind_get() call to load the
correct values into the various GRECTs in the Window structure.
int wx_info(ws,sp)
Window *ws;
char *sp;
This allocates sufficient memory to hold the string you pass it,
points the ws->name parameter in that direction, and then uses
wind_set() to point the window at that string. If you call it
again, it free()'s the original buffer and then allocates a new
one.
int wx_init(ws,vh,gl_wchar,gl_hchar)
Window *ws;
int vh,
gl_wchar,
gl_hchar;
This function sets up some variables that the wx_lib needs from
the system. The first is the VDI handle, which is placed in the
ws->vdih variable, for easy access. If it is less than 0, the
routine returns an error. The other two parameters are from the
graf_handle() call, and represent the height and width of a
character in the system font. This is necessary for the correct
calculation of the "cursor" position.
void wx_move(ws,x,y)
Window *ws;
int x,
y;
This call takes the x and y parameters you pass to it, and use
wind_set() to move the window to that position. They then
update all the relevant GRECTs in the Window structure.
int wx_name(ws,sp)
Window *ws;
char *sp;
This function acts exactly like wx_info() except it acts on the
name field of the window, instead of the info field.
void wx_new(ws)
Window *ws;
This is just a utility function that sets the members of ws to
some defaults that wx_open will accept gracefully.
int wx_open(ws)
Window *ws;
This function creates and opens the window that is described in
the Window structure ws. It updates all relevant GRECTs and
sets the x and y cursor positions to 0.
void wx_outstr(ws,sp)
Window *ws;
char *sp;
This is the most primitive of the output functions available.
It prints a string at the current position, with no regard for
whether it is on screen or not. It updates the x location of
the "cursor", and does nothing else. It doesn't understand any
special characters like \r, \n, \t, and will probably print them
as their printable counterparts.
void wx_printf(ws,sp,...)
Window *ws;
char *sp;
This is a windowed version of the old C warhorse, printf(). It
accepts any formatting characters that printf() will. It
runs the string through vsprintf() and then hands that string to
wx_puts() which knows about things like \n, \r, etc.
int wx_puts(ws,sp)
Window *ws;
char *sp;
This function is the slightly-less primitive sibling of
wx_outstr() and the slightly more primitive sibling of
wx_printf(). It knows about control chars like \n, \r, \t
(though at this time, it merely "eats" tabs, outputting a single
space in their stead), but doesn't know anything about
sophisticated formatting a la printf(). It does have to
allocate an internal buffer in order to process the string, and
will return FALSE if it is unable to.
void wx_setclip(ws)
Window *ws;
This function sets the clipping rectangle for the VDI
workstation to the current work area of the window in question.
void wx_settype(ws,t)
Window *ws;
int t;
This is functionally similar to the statement:
ws.type = INFO|MOVER|etc.
It is merely here for consistency in calling procedure.
Eventually I plan to have it so that you have no need to modify
variables in the Window structure directly, thereby making
things a bit more controlled and easy-to-follow. Obviously, the
value you use should be from whatever your GEM header file is,
ORing together different bit settings.
void wx_size(ws,w,h)
Window *ws;
int w,
h;
This function is much like wx_move(), with the caveat that it
sets the window to the width and height provided, rather than
the position. It updates all necessary variables and GRECTs.
What's coming:
That's it for t